/*
 * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.lang;

import java.io.IOException;

/**
 * 可以将字符序列和值追加到其中的对象。
 * Appendable接口必须实现，该类的实例旨在从java.util.Formatter接收格式化的输出。
 *
 * <p> 要添加的字符应该是Unicode字符表示中描述的有效的Unicode字符。
 * 注意，补充字符可以由多个16位字符值组成。
 *
 * <p> 对于多线程访问来说，Appendables不一定是安全的。
 * 线程安全是扩展和实现这个接口的类的职责。
 *
 * <p> 由于这个接口可以由具有不同风格的错误处理的现有类实现，因此不能保证错误将传播到调用程序。
 *
 * @since 1.5
 */
public interface Appendable {

    /**
     * 将指定的字符序列附加到此Appendable。
     *
     * <p> 根据实现字符序列csq的类的不同，可能不会追加整个序列。
     * 例如，如果csq是CharBuffer,
     * 然后，追加的子序列由缓冲区的位置和限制来定义。
     *
     * @param  csq
     *        要追加的字符序列。如果csq是null，那么四个字符“null”被附加到这个Appendable。
     *
     * @return  A reference to this <tt>Appendable</tt>
     *
     * @throws  IOException
     *          If an I/O error occurs
     */
    Appendable append(CharSequence csq) throws IOException;

    /**
     * 将指定字符序列的子序列附加到此Appendable。
     *
     * <p> 调用此方法的表单出来。当csq不为空时，append(csq, start,end)的行为与调用完全相同
     *
     * <pre>
     *     out.append(csq.subSequence(start, end)) </pre>
     *
     * @param  csq
     *         The character sequence from which a subsequence will be
     *         appended.  If <tt>csq</tt> is <tt>null</tt>, then characters
     *         will be appended as if <tt>csq</tt> contained the four
     *         characters <tt>"null"</tt>.
     *
     * @param  start
     *         The index of the first character in the subsequence
     *
     * @param  end
     *         The index of the character following the last character in the
     *         subsequence
     *
     * @return  A reference to this <tt>Appendable</tt>
     *
     * @throws  IndexOutOfBoundsException
     *          If <tt>start</tt> or <tt>end</tt> are negative, <tt>start</tt>
     *          is greater than <tt>end</tt>, or <tt>end</tt> is greater than
     *          <tt>csq.length()</tt>
     *
     * @throws  IOException
     *          If an I/O error occurs
     */
    Appendable append(CharSequence csq, int start, int end) throws IOException;

    /**
     * 将指定字符附加到Appendable。
     *
     * @param  c
     *         The character to append
     *
     * @return  A reference to this <tt>Appendable</tt>
     *
     * @throws  IOException
     *          If an I/O error occurs
     */
    Appendable append(char c) throws IOException;
}
